.env와 같은 민감한 파일을 Claude가 읽지 못하도록 커스텀 훅을 만들어 보겠습니다. 이는 개발 세션 중 환경 변수 및 기타 기밀 데이터를 훅으로 보호하는 실용적인 예시입니다.

훅 설정 구성하기

먼저 설정 파일에 훅을 구성해야 합니다. .claude/settings.local.json 파일을 열고 hooks 섹션을 찾으세요. 도구 호출이 실행되기 전에 가로채야 하므로 PreToolUse 훅을 생성합니다.

설정에는 두 가지 핵심 항목이 필요합니다:

• Matcher - 감시할 도구를 지정합니다
• Command - 해당 도구가 호출될 때 실행되는 스크립트입니다

matcher에는 .env 파일에 접근할 수 있는 읽기 및 grep 작업 모두를 감지하도록 설정합니다:

"matcher": "Read|Grep"

파이프 기호(|)는 OR 연산자로 동작하므로 두 도구 중 어느 것이든 트리거됩니다. command에는 Node.js 스크립트를 지정합니다:

"command": "node ./hooks/read_hook.js"

도구 호출 데이터 이해하기

Claude가 도구를 사용하려고 하면, 훅은 표준 입력을 통해 JSON 형태로 해당 호출에 대한 상세 정보를 받습니다. 이 데이터에는 다음이 포함됩니다:

• 세션 ID 및 트랜스크립트 경로
• 훅 이벤트 이름 (이 경우 PreToolUse)
• 도구 이름 (Read, Grep 등)
• 파일 경로를 포함한 도구 입력 파라미터

훅 스크립트는 이 데이터를 처리하여 작업을 계속 허용하거나 특정 코드로 종료하여 차단할 수 있습니다.

훅 스크립트 구현하기

훅 스크립트는 표준 입력에서 도구 호출 데이터를 읽고 Claude가 .env 파일에 접근하려는지 확인해야 합니다. 핵심 로직은 다음과 같습니다:

async function main() {
  const chunks = [];
  for await (const chunk of process.stdin) {
    chunks.push(chunk);
  }

  const toolArgs = JSON.parse(Buffer.concat(chunks).toString());

  // Extract the file path Claude is trying to read
  const readPath =
    toolArgs.tool_input?.file_path || toolArgs.tool_input?.path || "";

  // Check if Claude is trying to read the .env file
  if (readPath.includes('.env')) {
    console.error("You cannot read the .env file");
    process.exit(2);
  }
}

스크립트는 파일 경로에서 .env를 확인하고 발견되면 작업을 차단합니다. 코드 2로 종료하면 Claude는 오류 메시지를 받고 훅에 의해 작업이 차단되었음을 인식합니다.

훅 테스트하기

설정과 훅 스크립트를 저장한 후, 변경 사항을 적용하려면 Claude Code를 재시작하세요. 그런 다음 Claude에게 .env 파일을 읽어달라고 요청하여 테스트합니다.

Claude가 읽기 작업을 시도하면, 훅이 이를 가로채고 오류 메시지를 반환합니다. Claude는 작업이 차단되었음을 인식하고 읽기 훅이 파일 접근을 막았다는 사실을 설명합니다.

동일한 보호 기능이 grep 작업에도 적용됩니다. Claude가 .env 파일 내에서 검색을 시도하면 훅이 이 역시 차단합니다.

주요 장점

이 방식은 다음과 같은 여러 이점을 제공합니다:

• 선제적 보호 - 민감한 데이터가 읽히기 전에 접근을 차단합니다
• 투명한 동작 - Claude가 작업 실패 이유를 이해합니다
• 유연한 매칭 - 여러 도구(read, grep 등)에 작동합니다
• 명확한 피드백 - 의미 있는 오류 메시지를 제공합니다

이 예시는 .env 파일에 초점을 맞추고 있지만, 동일한 패턴으로 프로젝트의 민감한 파일이나 디렉터리를 보호할 수 있습니다. 여러 파일 패턴을 확인하거나 보안 요구 사항에 맞게 더 정교한 접근 제어를 구현하도록 로직을 확장할 수 있습니다.